/**
 *    Copyright (C) 2007-2009 DIVIS GmbH (http://www.divis-hagen.de/)
 * 
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License as published by the Free Software Foundation; either
 *    version 3 of the License, or (at your option) any later version.
 * 
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 * 
 *    You should have received a copy of the GNU Lesser General
 *    Public License along with this library; if not, write to the
 *    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 *    Boston, MA 02110-1301 USA
 */

package de.divis_hagen.json;


/**
 * <p>
 * The <code>JSONContext</code> represents the starting-point for JSON-related
 * operations. Currently this is limited to marshalling, but this will hopefully
 * improve.
 * </p>
 * <p>
 * An instance of this class can be obtained by calling
 * <code>JSONContext.newInstance(SomeClass.class);</code> with SomeClass being
 * the class of the objects this context should be associated with.
 * </p>
 * 
 * @author Aike J Sommer
 */
public abstract class JSONContext {

    /**
     * <p>
     * Obtain a new instance of JSONContext.
     * </p>
     * <p>
     * The <code>classes</code> should be annotated with JAXB-annotations.
     * There is no need to specify classes which are used as fields within 
     * an already specified class.
     * </p>
     * 
     * @param classes The classes of objects which should be marshalled with
     *                this instance.
     * @return An instance of JSONContext bound to the given
     *         <code>classes</code>.
     */
    public static JSONContext newInstance(Class... classes) {
        try {
            return (JSONContext) Class.forName("de.divis_hagen.json.JSONContextImpl").newInstance();
        } catch (Exception ex) {
            throw new RuntimeException(ex);
        }
    }

    
    /**
     * Create a marshaller that can write out objects of the classes given in
     * the call to {@link newInstance}.
     * 
     * @return A marshaller for transforming objects into JSON.
     */
    public abstract Marshaller createMarshaller();

    /**
     * If set to <code>true</code>, the children of the root-element
     * are output directly without marshalling the root-element.
     * Default is <code>false</code>.
     *
     * @param unwrap Wether the root-element should be unwrapped.
     */
    public abstract void setUnwrap(boolean unwrap);

    /**
     * Returns wether unwrapping the root-element is currently active.
     */
    public abstract boolean isUnwrap();


    /**
     * If set to <code>true</code>, names are properly escaped and all characters
     * are allowed. Otherwise names are mangled to camel-case.
     * Default is <code>true</code>.
     *
     * @param unwrap Wether the root-element should be unwrapped.
     */
    public abstract void setEscapeNames(boolean escape);

    /**
     * Returns wether escaping names is currently active.
     */
    public abstract boolean isEscapeNames();

}
